SST ShlWAPI StrToIntEx Function

	(SST) ShlWAPI.pas Version 1.08

Developer Reference

(SST)ShlWAPI StrToIntEx Function
Converts a literal, string representation of the integer part of a signed or unsigned number, in decimal or hexadecimal notation, into a signed, 32-bit integer value.

Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).

Syntax
	function StrToIntEx(pszString : LPCSTR; dwFlags : DWORD; piRet : PInteger) : BOOL;
	function StrToIntExA(pszString : LPCSTR; dwFlags : DWORD; piRet : PInteger) : BOOL; function StrToIntExW(pszString : LPCWSTR; dwFlags : DWORD; piRet : PInteger) : BOOL;

Parameters

pszString [in]

Pointer to a null-terminated string that represents a numerical value in decimal or hexadecimal notation.

dwFlag [in]

A combination of bit flags that determine how the function interprets the represntation of the number in the string. This is determined by the following flags:

STIF_DEFAULT	(= 0x00000000)	The string may represent the integer part of a positive or negative number from –2147483648 to 2147483647, in decimal notation only.
STIF_SUPPORT_HEX	(= 0x00000001)	The string may represent a 32-bit value from 0x00000000 to 0xFFFFFFFF, in hexadecimal notation.

Normally these flags could/would be combined by means of a bit-wise OR, but as, to date (September 2016), only two flags have been defined and documented, and these happen to have consecutive values, specifying the latter flag (STIF_SUPPORT_HEX) automatically combines both flags and the function will support both notations. However, this also requires that numbers in hexadecimal notation must be preceded by "0x" (without the quotation marks) for the function to be able to distinguish between the two notations.

piRet [out]

Pointer to, or address of, a signed, 32-bit integer variable, the function sets to the value it interpreted the string as representing.

Return Values
The function returns TRUE if it was able to convert at least the first digit of the numerical value the string represents, FALSE, if this failed.

Remarks
It should be borne in mind, that the function returns a signed, integer value, that is, strings representing values above 2147483647, in decimal notation, and 0x7FFFFFFF in hexadecimal notation, will result in negative values being returned.
Although, in principle, the function requires that the input string be composed only of the characters "0" .. "9", optionally preceded by a plus ("+") or minus ("-") sign, if only the STIF_DEFAULT flag is specified, it can be used to convert strings representing decimal numbers containing a decimal point (or comma) and a fractional part. However, the function does not recognize such strings as representations of floating point numbers, it merely ignores all parts of the string after the first invalid character it encoutners.
If the function is initialized to support both notations (i.e. the STIF_SUPPORT_HEX flag is specified), the function will accept input strings that, in addition to the characters already supported, contain the letters "a" through "f", and "x", as both lower and upper case characters.
If the input string represents a hexadecimal number, a minus sign ("-") has no influence on how the function sets bit 31 in the returned integer value. The function will therefore return 05 for both "-0x05" and "0x05", and not 0x80000005 for the former and 0x00000005 for the latter.
Separators such as commas, blanks, or periods, frequently used to group digits in numbers larger than 999, will cause the function to return erroneous results. However, unlike the ShlWAPI function StrToInt, StrToIntEx does ignore leading white space characters (note the plural !) in the input string (i.e. leading blanks do not cause the function to fail).
The function was developed for source code written in C/C++ and therefore does not recognize the Pascal prefix for numbers in hexadecimal notation ("$").

Example
PROCEDURE TForm4.TestShlWAPIStrToIntEx(Sender : TObject); VAR numstr : STRING; VAR flags : DWORD; VAR number : INTEGER; VAR apiretval : BOOL; VAR newinfoline : STRING; BEGIN numstr := ''; flags := 0; //(= STIF_DEFAULT = $00000000;); number := 0; apiretval := FALSE; newinfoline := ''; numstr := '22000'; //flags := STIF_DEFAULT; //= 0, set in var initialization apiretval := StrToIntEx(PChar(numstr), flags, @number); newinfoline := 'StrToIntEx called with "' + numstr + '" returned : '; IF apiretval = TRUE THEN newinfoline := newinfoline + 'TRUE, ' ELSE newinfoline := newinfoline + 'FALSE, '; newinfoline := newinfoline + IntToStr(number) + ' (0x' + IntToHex(number, 8) + ')'; Memo1.Lines.Add(newinfoline); number := 0; apiretval := FALSE; numstr := '3,300,100'; //flags := STIF_DEFAULT; //= 0, set in var initialization apiretval := StrToIntEx(PChar(numstr), flags, @number); newinfoline := 'StrToIntEx called with "' + numstr + '" returned : '; IF apiretval = TRUE THEN newinfoline := newinfoline + 'TRUE, ' ELSE newinfoline := newinfoline + 'FALSE, '; newinfoline := newinfoline + IntToStr(number) + ' (0x' + IntToHex(number, 8) + ')'; Memo1.Lines.Add(newinfoline); number := 0; apiretval := FALSE; numstr := '44.127.958'; //flags := STIF_DEFAULT; //= 0, set in var initialization apiretval := StrToIntEx(PChar(numstr), flags, @number); newinfoline := 'StrToIntEx called with "' + numstr + '" returned : '; IF apiretval = TRUE THEN newinfoline := newinfoline + 'TRUE, ' ELSE newinfoline := newinfoline + 'FALSE, '; newinfoline := newinfoline + IntToStr(number) + ' (0x' + IntToHex(number, 8) + ')'; Memo1.Lines.Add(newinfoline); number := 0; apiretval := FALSE; numstr := ' 330010'; //flags := STIF_DEFAULT; //= 0, set in var initialization apiretval := StrToIntEx(PChar(numstr), flags, @number); newinfoline := 'StrToIntEx called with "' + numstr + '" returned : '; IF apiretval = TRUE THEN newinfoline := newinfoline + 'TRUE, ' ELSE newinfoline := newinfoline + 'FALSE, '; newinfoline := newinfoline + IntToStr(number) + ' (0x' + IntToHex(number, 8) + ')'; Memo1.Lines.Add(newinfoline); number := 0; apiretval := FALSE; numstr := FloatToStr(8888.77); apiretval := StrToIntEx(PChar(numstr), flags, @number); newinfoline := 'StrToIntEx called with "' + numstr + '" returned : '; IF apiretval = TRUE THEN newinfoline := newinfoline + 'TRUE, ' ELSE newinfoline := newinfoline + 'FALSE, '; newinfoline := newinfoline + IntToStr(number) + ' (0x' + IntToHex(number, 8) + ')'; Memo1.Lines.Add(newinfoline); number := 0; apiretval := FALSE; numstr := 'FFFFFFFF'; flags := 1; //(= STIF_SUPPORT_HEX = $00000001;); apiretval := StrToIntEx(PChar(numstr), flags, @number); newinfoline := 'StrToIntEx called with "' + numstr + '" returned : '; IF apiretval = TRUE THEN newinfoline := newinfoline + 'TRUE, ' ELSE newinfoline := newinfoline + 'FALSE, '; newinfoline := newinfoline + IntToStr(number) + ' (0x' + IntToHex(number, 8) + ')'; Memo1.Lines.Add(newinfoline); number := 0; apiretval := FALSE; numstr := 'AA11BB22'; flags := 1; //(= STIF_SUPPORT_HEX = $00000001;); apiretval := StrToIntEx(PChar(numstr), flags, @number); newinfoline := 'StrToIntEx called with "' + numstr + '" returned : '; IF apiretval = TRUE THEN newinfoline := newinfoline + 'TRUE, ' ELSE newinfoline := newinfoline + 'FALSE, '; newinfoline := newinfoline + IntToStr(number) + ' (0x' + IntToHex(number, 8) + ')'; Memo1.Lines.Add(newinfoline); number := 0; apiretval := FALSE; numstr := '0xCC33DD44'; flags := 1; //(= STIF_SUPPORT_HEX = $00000001;); apiretval := StrToIntEx(PChar(numstr), flags, @number); newinfoline := 'StrToIntEx called with "' + numstr + '" returned : '; IF apiretval = TRUE THEN newinfoline := newinfoline + 'TRUE, ' ELSE newinfoline := newinfoline + 'FALSE, '; newinfoline := newinfoline + IntToStr(number) + ' (0x' + IntToHex(number, 8) + ')'; Memo1.Lines.Add(newinfoline); number := 0; apiretval := FALSE; numstr := '0X' + IntToHex($EE55FF66, 8); flags := 1; //(= STIF_SUPPORT_HEX = $00000001;); apiretval := StrToIntEx(PChar(numstr), flags, @number); newinfoline := 'StrToIntEx called with "' + numstr + '" returned : '; IF apiretval = TRUE THEN newinfoline := newinfoline + 'TRUE, ' ELSE newinfoline := newinfoline + 'FALSE, '; newinfoline := newinfoline + IntToStr(number) + ' (0x' + IntToHex(number, 8) + ')'; Memo1.Lines.Add(newinfoline); number := 0; apiretval := FALSE; numstr := ' 0X' + IntToHex($AF15BE72, 8); flags := 1; //(= STIF_SUPPORT_HEX = $00000001;); apiretval := StrToIntEx(PChar(numstr), flags, @number); newinfoline := 'StrToIntEx called with "' + numstr + '" returned : '; IF apiretval = TRUE THEN newinfoline := newinfoline + 'TRUE, ' ELSE newinfoline := newinfoline + 'FALSE, '; newinfoline := newinfoline + IntToStr(number) + ' (0x' + IntToHex(number, 8) + ')'; Memo1.Lines.Add(newinfoline); number := 0; apiretval := FALSE; numstr := '$' + IntToHex($1B52F104, 8); flags := 1; //(= STIF_SUPPORT_HEX = $00000001;); apiretval := StrToIntEx(PChar(numstr), flags, @number); newinfoline := 'StrToIntEx called with "' + numstr + '" returned : '; IF apiretval = TRUE THEN newinfoline := newinfoline + 'TRUE, ' ELSE newinfoline := newinfoline + 'FALSE, '; newinfoline := newinfoline + IntToStr(number) + ' (0x' + IntToHex(number, 8) + ')'; Memo1.Lines.Add(newinfoline); number := 0; apiretval := FALSE; Memo1.Lines.Add(''); END;
The above example produces the following output:
StrToIntEx called with "22000" returned : TRUE, 22000 (0x000055F0) StrToIntEx called with "3,300,100" returned : TRUE, 3 (0x00000003) StrToIntEx called with "44.127.958" returned : TRUE, 44 (0x0000002C) StrToIntEx called with " 330010" returned : TRUE, 330010 (0x0005091A) StrToIntEx called with "8888.77" returned : TRUE, 8888 (0x000022B8) StrToIntEx called with "FFFFFFFF" returned : FALSE, 0 (0x00000000) StrToIntEx called with "AA11BB22" returned : FALSE, 0 (0x00000000) StrToIntEx called with "0xCC33DD44" returned : TRUE, -869016252 (0xCC33DD44) StrToIntEx called with "0XEE55FF66" returned : TRUE, -296353946 (0xEE55FF66) StrToIntEx called with " 0XAF15BE72" returned : TRUE, -1357529486 (0xAF15BE72) StrToIntEx called with "$1B52F104" returned : FALSE, 0 (0x00000000)

Requirements
Unit:	Declared and imported in (SST)ShlWAPI.pas
Library:	(SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode:	Implemented as ANSI (StrToIntEx and StrToIntExA) and Unicode (StrToIntExW) functions.
Min. ShlWAPI.dll version according to MS SDK doc.:	4.71
Min. ShlWAPI.dll version based on SST research:	4.71
Min. OS version(s) according to Microsoft SDK doc.:	Windows 2000, Windows NT 4.0 with Internet Explorer 4.0, Windows 98, Windows 95 with Internet Explorer 4.0
Min. OS version(s) according to SST research.:	Windows NT 4.0 with IE 4.0, Windows 95 with IE 4.0, Windows 98, Windows 2000 and later

See Also
StrToInt.

Windows APIs: StrToInt, StrToInt64Ex, StrToIntEx